✨ feat(reviewer-lane): ship the adjudication contract as a template (#5617 item 2) - #5720

Summary

Item 2 of #5617 — the embedded kick template — which is the last of the four deferred follow-ups still outstanding, and the one @clubanderson's dispatch on the issue asked for. The reviewer lane's adjudication contract moves from a compiled-in string into pkg/policies/defaults/reviewer-lane.md.

The lane reaches its prompt by role, not by kick_template: an operator enables it by adding a cadence agent with role: reviewer — any name, no kick_template — so the ordinary resolution order never reached it and the contract was changeable only by rebuilding the binary. It now resolves through the same paths as every other template, so an operator-saved copy or a policies-checkout copy wins over the embedded default.

This is an extraction, and that is asserted rather than claimed

TestReviewerLaneTemplate_ByteIdenticalToBuilder renders the template and the builder it came from and compares them byte for byte, at both close-authority levels, reporting the first differing line on failure.

That test is the load-bearing one. Every line of this contract is a rule an agent follows against a human queue, so "the template looks right" is not a standard worth shipping — and the pre-existing TestBuildReviewerMessage_ContractAtL5 can only check the ~25 strings somebody thought to list. Those existing tests now exercise the template path too, since that is what buildReviewerMessage returns, which is the parity coverage step 3 of the dispatch asked for.

Three decisions deliberately stay in Go

The template is editable — that is the point of shipping one. These are not wording, so an override must not be able to reach them:

So the worst an override can do is change the wording of a kick that was already going to be sent. All three are pinned by tests that install a rogue operator template — one that unconditionally issues a contract and offers gh pr close — and prove it cannot wake the lane, invent work, or grant close authority.

Two smaller decisions worth flagging

The work list is passed into the substitution, not recomputed inside it. buildReviewerMessage has already gated on that exact list; re-reading ci-failing.json during rendering would reopen a window where a rewrite between the two reads renders a full adjudication contract over an empty list. That needed a substituteTemplateWithVars variant taking caller-supplied ${VAR}s — in which the built-ins win a name clash, so no call site can redefine ${GH_AUTH}. A test pins that.

The compiled-in contract is kept as the resolution fallback. Step 4 of the dispatch says to remove it "only after template coverage is green"; I have kept it, because a stripped binary or an override that reads as empty must not leave the reviewer with no contract, which is worse than the previous wording. The parity test is what makes keeping both safe — they cannot drift without failing it. Removing it is a follow-up, not this PR.

Cluster claimed (files/functions)

• src/pkg/policies/defaults/reviewer-lane.md (new) — the extracted contract.
• src/pkg/scheduler/reviewer_lane.go — reviewerLaneTemplate, reviewerKickHeader, renderReviewerLaneTemplate, reviewerCloseAuthority, and buildReviewerMessageHardcoded (the former body, unchanged text, now the fallback).
• src/pkg/scheduler/scheduler.go — substituteTemplateWithVars; substituteTemplateWithPolicy delegates to it with nil, so every existing caller is untouched.
• src/pkg/scheduler/reviewer_lane_template_test.go (new, 6 tests), src/docs/agent-configuration.md, CHANGELOG.md.

No behaviour change: this is the "pure template extraction plus parity tests" scope the dispatch specified.

Validation

• go build ./..., go vet ./pkg/scheduler/ ./pkg/policies/, gofmt -l clean on every file I touched. (gofmt flags three other pkg/scheduler test files — pre-existing drift, untouched here.)

• go test ./pkg/scheduler/ ./pkg/policies/ — both packages pass in full, including every pre-existing reviewer-lane contract test.

• src/scripts/check-docs-links.py: all links and anchors resolve.

• Mutation-checked, and both mutations are caught by the new tests and by the pre-existing ones:

  Mutation	Caught by
  Drop one INVARIANT clause from the template	_ByteIdenticalToBuilder and TestBuildReviewerMessage_ContractAtL5
  Resolve the template before the ACMM gate	_GatesAreNotTemplated and TestBuildReviewerMessage_ACMMGateDormantBelowL5 and _EmptyQueueStandsDown

Related issues

Refs #5617 (item 2 of 4 — items 1, 3 and 4 landed in #5634 and #5682). Related: #5480 (the reviewer lane), #5511 (the one-pass ladder the contract encodes).

Testing

• cd src && go build ./...
• cd src && go test ./... — ran ./pkg/scheduler/ and ./pkg/policies/ in full (the only packages touched); both pass.

— hive: backend=claude model=claude-opus-5